.TH std::ranges::remove_copy,std::ranges::remove_copy_if,std::ranges::remove_copy_result, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::ranges::remove_copy,std::ranges::remove_copy_if,std::ranges::remove_copy_result, \- std::ranges::remove_copy,std::ranges::remove_copy_if,std::ranges::remove_copy_result,

.SH Synopsis

   Defined in header <algorithm>
   Call signature
   template< std::input_iterator I, std::sentinel_for<I> S,

             std::weakly_incrementable O, class T, class Proj =
   std::identity >
   requires std::indirectly_copyable<I, O> &&                           (since
            std::indirect_binary_predicate                              C++20)
                <ranges::equal_to, std::projected<I, Proj>,             (until
   const T*>                                                            C++26)
   constexpr remove_copy_result<I, O>

       remove_copy( I first, S last, O result, const T& value,
   Proj proj = {} );
   template< std::input_iterator I, std::sentinel_for<I> S,

             std::weakly_incrementable O, class Proj =
   std::identity,
             class T = std::projected_value_t<I, Proj> >
   requires std::indirectly_copyable<I, O> &&                           (since
            std::indirect_binary_predicate                              C++26)
                <ranges::equal_to, std::projected<I, Proj>,
   const T*>
   constexpr remove_copy_result<I, O>

       remove_copy( I first, S last, O result, const T& value,
   Proj proj = {} );
   template< ranges::input_range R,

             std::weakly_incrementable O, class T, class Proj =
   std::identity >
   requires std::indirectly_copyable<ranges::iterator_t<R>, O>
   &&                                                                           (since
            std::indirect_binary_predicate                                      C++20)
                <ranges::equal_to,                                              (until
                 std::projected<ranges::iterator_t<R>, Proj>,                   C++26)
   const T*>
   constexpr remove_copy_result<ranges::borrowed_iterator_t<R>,
   O>

       remove_copy( R&& r, O result, const T& value, Proj proj
   = {} );
   template< ranges::input_range R,

             std::weakly_incrementable O, class Proj =          \fB(1)\fP
   std::identity,
             class T =
   std::projected_value_t<ranges::iterator_t<R>, Proj> >
   requires std::indirectly_copyable<ranges::iterator_t<R>, O>
   &&                                                                           (since
            std::indirect_binary_predicate                                      C++26)
                <ranges::equal_to,
                 std::projected<ranges::iterator_t<R>, Proj>,
   const T*>
   constexpr remove_copy_result<ranges::borrowed_iterator_t<R>,
   O>

       remove_copy( R&& r, O result, const T& value, Proj proj      \fB(2)\fP
   = {} );
   template< std::input_iterator I, std::sentinel_for<I> S,

             std::weakly_incrementable O, class Proj =
   std::identity,
             std::indirect_unary_predicate<std::projected<I,                    (since
   Proj>> Pred >                                                        \fB(3)\fP     C++20)
   requires std::indirectly_copyable<I, O>
   constexpr remove_copy_if_result<I, O>

       remove_copy_if( I first, S last, O result, Pred pred,
   Proj proj = {} );
   template< ranges::input_range R,

             std::weakly_incrementable O, class Proj =
   std::identity,
             std::indirect_unary_predicate<
                 std::projected<ranges::iterator_t<R>, Proj>>                   (since
   Pred >                                                               \fB(4)\fP     C++20)
   requires std::indirectly_copyable<ranges::iterator_t<R>, O>
   constexpr
   remove_copy_if_result<ranges::borrowed_iterator_t<R>, O>

       remove_copy_if( R&& r, O result, Pred pred, Proj proj =
   {} );
.SH Helper types
   template< class I, class O >                                         \fB(5)\fP     (since
   using remove_copy_result = ranges::in_out_result<I, O>;                      C++20)
   template< class I, class O >                                         \fB(6)\fP     (since
   using remove_copy_if_result = ranges::in_out_result<I, O>;                   C++20)

   Copies elements from the source range [first, last), to the destination range
   beginning at result, omitting the elements which (after being projected by proj)
   satisfy specific criteria. The behavior is undefined if the source and destination
   ranges overlap.

   1) Ignores all elements that are equal to value.
   3) Ignores all elements for which predicate pred returns true.
   2,4) Same as (1,3), but uses r as the source range, as if using ranges::begin(r) as
   first, and ranges::end(r) as last.

   The function-like entities described on this page are niebloids, that is:

     * Explicit template argument lists cannot be specified when calling any of them.
     * None of them are visible to argument-dependent lookup.
     * When any of them are found by normal unqualified lookup as the name to the left
       of the function-call operator, argument-dependent lookup is inhibited.

   In practice, they may be implemented as function objects, or with special compiler
   extensions.

.SH Parameters

   first, last - the source range of elements
   r           - the source range of elements
   result      - the beginning of the destination range
   value       - the value of the elements not to copy
   comp        - the binary predicate to compare the projected elements
   proj        - the projection to apply to the elements

.SH Return value

   {last, result + N}, where N is the number of elements copied.

.SH Complexity

   Exactly ranges::distance(first, last) applications of the corresponding predicate
   comp and any projection proj.

.SH Notes

   The algorithm is stable, i.e. preserves the relative order of the copied elements.

             Feature-test macro           Value    Std              Feature
   __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for
                                                         algorithms (1,2)

.SH Possible implementation

                                        remove_copy
  struct remove_copy_fn
  {
      template<std::input_iterator I, std::sentinel_for<I> S,
               std::weakly_incrementable O, class Proj = std::identity,
               class T = std::projected_value_t<I, Proj>>
      requires std::indirectly_copyable<I, O> &&
               std::indirect_binary_predicate<ranges::equal_to,
                                              std::projected<I, Proj>, const T*>
      constexpr ranges::remove_copy_result<I, O>
          operator()(I first, S last, O result, const T& value, Proj proj = {}) const
      {
          for (; !(first == last); ++first)
              if (value != std::invoke(proj, *first))
              {
                  *result = *first;
                  ++result;
              }
          return {std::move(first), std::move(result)};
      }

      template<ranges::input_range R,
               std::weakly_incrementable O, class Proj = std::identity,
               class T = std::projected_value_t<ranges::iterator_t<R>, Proj>>
      requires std::indirectly_copyable<ranges::iterator_t<R>, O> &&
               std::indirect_binary_predicate<ranges::equal_to,
               std::projected<ranges::iterator_t<R>, Proj>, const T*>
      constexpr ranges::remove_copy_result<ranges::borrowed_iterator_t<R>, O>
          operator()(R&& r, O result, const T& value, Proj proj = {}) const
      {
          return (*this)(ranges::begin(r), ranges::end(r), std::move(result), value,
                         std::move(proj));
      }
  };

  inline constexpr remove_copy_fn remove_copy {};
                                       remove_copy_if
  struct remove_copy_if_fn
  {
      template<std::input_iterator I, std::sentinel_for<I> S, std::weakly_incrementable O,
               class Proj = std::identity,
               std::indirect_unary_predicate<std::projected<I, Proj>> Pred>
      requires std::indirectly_copyable<I, O>
      constexpr ranges::remove_copy_if_result<I, O>
          operator()(I first, S last, O result, Pred pred, Proj proj = {}) const
      {
          for (; first != last; ++first)
              if (false == std::invoke(pred, std::invoke(proj, *first)))
              {
                  *result = *first;
                  ++result;
              }
          return {std::move(first), std::move(result)};
      }

      template<ranges::input_range R, std::weakly_incrementable O,
               class Proj = std::identity,
               std::indirect_unary_predicate<
                   std::projected<ranges::iterator_t<R>, Proj>> Pred>
      requires std::indirectly_copyable<ranges::iterator_t<R>, O>
      constexpr ranges::remove_copy_if_result<ranges::borrowed_iterator_t<R>, O>
          operator()(R&& r, O result, Pred pred, Proj proj = {}) const
      {
          return (*this)(ranges::begin(r), ranges::end(r), std::move(result),
                         std::move(pred), std::move(proj));
      }
  };

  inline constexpr remove_copy_if_fn remove_copy_if {};

.SH Example


// Run this code

 #include <algorithm>
 #include <array>
 #include <complex>
 #include <iomanip>
 #include <iostream>
 #include <iterator>
 #include <string_view>
 #include <vector>

 void println(const auto rem, const auto& v)
 {
     std::cout << rem << ' ';
     for (const auto& e : v)
         std::cout << e << ' ';
     std::cout << '\\n';
 }

 int main()
 {
     // Filter out the hash symbol from the given string.
     const std::string_view str{"#Small #Buffer #Optimization"};
     std::cout << "before: " << std::quoted(str) << '\\n';

     std::cout << "after:  \\"";
     std::ranges::remove_copy(str.begin(), str.end(),
                              std::ostream_iterator<char>(std::cout), '#');
     std::cout << "\\"\\n";

     // Copy only the complex numbers with positive imaginary part.
     using Ci = std::complex<int>;
     constexpr std::array<Ci, 5> source
     {
         Ci{1, 0}, Ci{0, 1}, Ci{2, -1}, Ci{3, 2}, Ci{4, -3}
     };
     std::vector<std::complex<int>> target;

     std::ranges::remove_copy_if
     (
         source,
         std::back_inserter(target),
         [](int imag) { return imag <= 0; },
         [](Ci z) { return z.imag(); }
     );

     println("source:", source);
     println("target:", target);

     std::vector<std::complex<float>> nums{{2, 2}, {1, 3}, {4, 8}, {1, 3}};
     std::vector<std::complex<double>> outs;
     #ifdef __cpp_lib_algorithm_default_value_type
         std::remove_copy(nums.cbegin(), nums.cend(), std::back_inserter(outs),
                          {1, 3}); // T gets deduced to std::complex<float>
     #else
         std::remove_copy(nums.cbegin(), nums.cend(), std::back_inserter(outs),
                          std::complex<float>{1, 3});
     #endif
     println("nums:  ", nums);
     println("outs:  ", outs);
 }

.SH Output:

 before: "#Small #Buffer #Optimization"
 after:  "Small Buffer Optimization"
 source: (1,0) (0,1) (2,-1) (3,2) (4,-3)
 target: (0,1) (3,2)
 nums:   (2,2) (1,3) (4,8) (1,3)
 outs:   (2,2) (4,8)

.SH See also

   ranges::remove
   ranges::remove_if       removes elements satisfying specific criteria
   (C++20)                 (niebloid)
   (C++20)
   ranges::copy
   ranges::copy_if         copies a range of elements to a new location
   (C++20)                 (niebloid)
   (C++20)
   ranges::copy_n          copies a number of elements to a new location
   (C++20)                 (niebloid)
   ranges::copy_backward   copies a range of elements in backwards order
   (C++20)                 (niebloid)
   ranges::replace_copy    copies a range, replacing elements satisfying specific
   ranges::replace_copy_if criteria with another value
   (C++20)                 (niebloid)
   (C++20)
   ranges::reverse_copy    creates a copy of a range that is reversed
   (C++20)                 (niebloid)
   ranges::rotate_copy     copies and rotate a range of elements
   (C++20)                 (niebloid)
   ranges::unique_copy     creates a copy of some range of elements that contains no
   (C++20)                 consecutive duplicates
                           (niebloid)
   remove_copy             copies a range of elements omitting those that satisfy
   remove_copy_if          specific criteria
                           \fI(function template)\fP
